Related PRs:

https://github.com/ibexa/scheduler/pull/111

Description:

AdapterNormalizer

A new normalizer with low priority is implemented called AdapterNormalizer that handles data normalization or visiting data using the existing visitors. Currently, the visitors are prioritized over incoming (new) normalizers.

Unfortunately, the problem is that in order to visit value objects the Visitor and Generator have to be created and passed as arguments to ValueObjectVisitor instance.

        $valueObjectVisitor->visit($visitor, $generator, $object);

Ibexa\Contracts\Rest\Output\ValueObjectVisitorDispatcher

It is deleted now and the responsibility for finding a proper visitor is moved to the newly introduced ValueObjectVisitorResolverInterface.

Ibexa\Contracts\Rest\OutputVisitor

The visitValueObject method has to behave exactly the same as before as it's used throughout the app so we should keep BC here. I don't think we can change it to use normalizer as it uses the original Visitor's generator.

Concept made by Paweł.

Documentation:

From now on the responses generated by Ibexa will be normalized and encoded by Symfony's Serializer https://symfony.com/doc/5.x/serializer.html. This is a change from the old way of doing things when the only responsibility laid on Json\Generator or Xml\Generator to handle things, so normalizing and encoding depending on the generator used. Currently, the generators are responsible for generating JsonObject which is a representation of data one wants to normalize and they allow to prepare a context for Symfony's encoder and their purpose is to keep BC for older Ibexa data structures.

How a developer can take advantage of the new implementation?
Instead of writing a dedicated ValueObjectVisitor that handles generation of JsonObject inside Generator\Xml or Generator\Json (for example https://github.com/ibexa/rest/blob/main/src/lib/Server/Output/ValueObjectVisitor/Author.php) one can write a dedicated normalizer: https://symfony.com/doc/5.x/components/serializer.html#component-serializer-normalizers. Example:

Imagine we have a new data structure: TestDataObject with the following definition:

use Ibexa\Contracts\Core\Repository\Values\Content\Location;

final readonly class TestDataObject
{
    public function __construct(
        public string $string,
        public int $int,
        public ?Location $apiLocation = null,
    ) {
    }
}

One can notice the Location object which in fact is an instance of Ibexa's Location, it hints that Symfony's Serializer will be able to work with such data. Instead of writing a dedicated ValueObjectVisitor one can introduce a normalizer:

final class TestDataObjectNormalizer implements NormalizerInterface, NormalizerAwareInterface
{
    use NormalizerAwareTrait;

    /**
     * @return array<string, mixed>
     */
    public function normalize(mixed $object, ?string $format = null, array $context = []): array
    {
        assert($object instanceof TestDataObject);

        $data = [
            'string' => $object->string,
            'int' => $object->int,
            'location' => null,
        ];

        if ($object->apiLocation instanceof Location) {
            $normalizedLocation = $this->normalizer->normalize($object->apiLocation, $format);
            $data['location'] = $normalizedLocation['#'] ?? $normalizedLocation['Location'] ?? null;
        }

        return $data;
    }

    public function supportsNormalization(mixed $data, ?string $format = null): bool
    {
        return $data instanceof TestDataObject;
    }
}

We can notice how easy it is to normalize Ibexa's Location object, one simply does:

$normalizedLocation = $this->normalizer->normalize($object->apiLocation, $format);

and because of how internal Ibexa's AdapterNormalizer works it will provide already normalized data that will be normalized using backwards-compatible value object visitors. This is really important and powerful mechanism as we are allowed to normalize both old data that use value object visitors and new data that don't have value object visitors but have dedicated normalizers instead together.

Finally, to obtain the final encoded data in json/xml format from PHP object representation it really comes down to:

        $dataObject = new TestDataObject(
            'some_string',
            1,
            $this->locationService->loadLocation(2),
        );

        $serializedData = $this->serializer->serialize($dataObject, 'json');

Symfony's Serializer will work internally with Ibexa's Generators and Value Object Visitors to normalize and encode data for the specific format (json in case of the above example) - the final result can be previewed here: https://github.com/ibexa/rest/blob/23bb684b4dd9d68ec5537d5fd125ebdaf26a983b/tests/integration/Serializer/_snapshot/TestDataObject.json.

One must remember that normalizers that normalize Ibexa's data objects has to be registered with the following tag:

services:
    App\Normalizer\TestDataObjectNormalizer:
        tags:
            - { name: ibexa.rest.serializer.normalizer }

It is important for the app safety and performance to NOT autoconfigure these normalizers. If autoconfigured those will receive serializer.normalizer tags and will be injected into the main application serializer, which is ill-advised.

QA:

Technically speaking nothing for the end-user should change, app should behave the same as before. It's definitely worth checking how REST endpoints behave with this implementation (including Scheduler ones) + testing some test data using normalizer as shown in the description above.